Skills 执行机制概述#
Skills 的执行机制是理解其工作原理的核心。本节将深入探讨 Skills 如何被调用、解析和执行，以及整个执行流程中的关键环节。
执行流程概览#
Skills 的执行流程可以分为以下几个主要阶段：
graphA[用户请求] --> B[主代理接收] B --> C{选择 Skill} C --> D[加载 Skill 定义] D --> E[解析参数和上下文] E --> F[执行 Skill 逻辑] F --> G[调用工具] G --> H[处理结果] H --> I[返回输出] I --> J[主代理整合] J --> K[呈现给用户]
1. Skill 调用#
调用方式#
1.1 直接调用
用户直接指定要使用的 Skill：
bash# 命令行调用 claude --skill code-review --file src/main.py # 交互式调用 /skill code-review
1.2 自动选择
主代理根据任务自动选择合适的 Skill：
markdown## 自动选择流程 ### 用户请求 "帮我审查这段代码的质量" ### 主代理分析 1. 理解用户意图 2. 搜索相关 Skills 3. 匹配最合适的 Skill 4. 执行并返回结果
1.3 嵌套调用
一个 Skill 调用另一个 Skill：
markdown## 嵌套调用示例 ### Skill: 部署应用 #### 执行步骤 1. 调用代码审查 Skill 2. 调用测试运行 Skill 3. 调用部署 Skill 4. 生成部署报告
参数传递#
markdown## 参数传递方式 ### 命令行参数 ```bash claude --skill code-gen --language python --framework flask
交互式输入#
markdown> 请提供以下信息： > - 编程语言：Python > - 框架：Flask > - 功能描述：用户认证系统
配置文件#
yamlskills: code-gen: language: python framework: flask
上下文推断#
markdown## 从上下文推断 - 从文件扩展名推断语言 - 从项目配置推断框架 - 从代码风格推断风格偏好 - 从历史记录推断用户偏好
2. Skill 加载#
加载过程#
2.1 定位 Skill
markdown## Skill 定位流程 ### 搜索顺序 1. 项目本地 Skills 2. 用户自定义 Skills 3. 系统内置 Skills 4. 插件提供的 Skills
2.2 读取定义
markdown## Skill 定义结构 ### 元数据 ```yaml name: code-review version: 1.2.0 description: 自动审查代码质量 author: Claude Code Team
输入规范#
yamlinputs: file: type: string required: true description: 要审查的文件路径 strict: type: boolean required: false default: false description: 是否严格模式
执行逻辑#
markdown## 执行步骤 1. 读取代码文件 2. 分析代码结构 3. 检查代码质量 4. 生成审查报告
2.3 验证定义
markdown## 定义验证 ### 验证项 - 必需字段是否存在 - 参数类型是否正确 - 默认值是否有效 - 引用是否存在 - 语法是否正确 ### 验证失败处理 - 返回错误信息 - 提供修复建议 - 阻止 Skill 执行
缓存机制#
markdown## Skill 缓存 ### 缓存内容 - Skill 定义 - 解析结果 - 依赖关系 ### 缓存策略 - 内存缓存（会话级别） - 磁盘缓存（持久化） - 版本控制（基于 Skill 版本） ### 缓存失效 - Skill 定义更新 - 依赖变更 - 手动清除 ## 3. 上下文解析 ### 上下文类型 #### 3.1 项目上下文 ## 3. 上下文管理 ### 3.1 项目上下文 ```markdown ## 项目上下文 ### 包含信息 - 项目结构 - 文件列表 - 依赖关系 - 配置文件 - 技术栈 ### 获取方式 - 读取项目配置 - 扫描文件系统 - 分析依赖文件 - 检测技术栈
3.2 代码上下文
markdown## 代码上下文 ### 包含信息 - 代码结构 - 函数定义 - 类定义 - 导入关系 - 调用关系 ### 获取方式 - 解析源代码 - 构建抽象语法树 - 分析符号表 - 追踪依赖关系
3.3 用户上下文
markdown## 用户上下文 ### 包含信息 - 用户偏好 - 历史操作 - 常用命令 - 学习进度 ### 获取方式 - 读取用户配置 - 查看历史记录 - 分析使用模式 - 记录用户反馈
上下文收集#
markdown## 上下文收集策略 ### 按需收集 - 只收集需要的上下文 - 避免不必要的开销 - 动态调整收集范围 ### 增量收集 - 基于已有上下文 - 只收集变更部分 - 减少重复工作 ### 并行收集 - 同时收集多个上下文 - 提高收集效率 - 合理分配资源
上下文限制#
markdown## 上下文限制 ### 大小限制 - 上下文窗口大小 - Token 限制 - 内存限制 ### 处理策略 - 优先级排序 - 摘要压缩 - 分批处理 - 流式处理
4. Skill 执行#
执行模式#
4.1 同步执行
markdown## 同步执行 ### 特点 - 阻塞等待结果 - 适用于快速任务 - 简单的错误处理 ### 示例 ```python result = execute_skill("code-review", file="src/main.py") print(result)
bash#### 4.2 异步执行 ```markdown ## 异步执行 ### 特点 - 非阻塞执行 - 适用于耗时任务 - 复杂的错误处理 ### 示例 ```python task = execute_skill_async("code-review", file="src/main.py") # 继续其他工作 result = await task.get_result()
bash#### 4.3 流式执行 ```markdown ## 流式执行 ### 特点 - 实时返回结果 - 适用于大输出任务 - 更好的用户体验 ### 示例 ```python for chunk in execute_skill_stream("code-review", file="src/main.py"): print(chunk, end='')
bash### 执行步骤 #### 4.4 步骤分解 ```markdown ## Skill: 代码审查 ### 执行步骤 1. **准备阶段** - 验证输入参数 - 加载代码文件 - 初始化审查规则 2. **分析阶段** - 解析代码结构 - 分析代码质量 - 检查安全问题 3. **评估阶段** - 评估代码复杂度 - 验证最佳实践 - 计算质量分数 4. **生成阶段** - 生成问题列表 - 提供改进建议 - 创建审查报告 5. **验证阶段** - 验证报告完整性 - 检查建议可行性 - 确保输出格式正确
错误处理#
4.5 错误类型
markdown## 错误类型 ### 输入错误 - 参数缺失 > - 参数类型错误 > - 参数值无效 ### 执行错误 > - 文件不存在 > - 权限不足 > - 资源不足 ### 逻辑错误 > - 无法解析代码 > - 分析失败 > - 生成失败 #### 4.6 错误处理策略 ~~~markdown markdown ## 错误处理策略 ### 立即失败 - 遇到错误立即停止 - 返回错误信息 - 不继续执行 ### 跳过继续 - 记录错误 - 跳过当前步骤 - 继续执行 ### 重试机制 - 自动重试 - 指数退避 - 最大重试次数 ### 降级处理 - 使用备用方案 - 简化执行逻辑 - 返回部分结果 ## 5. 工具调用 ### 工具调用机制 #### 5.1 工具选择 ```markdown ## 工具选择 ### 选择依据 > - 任务需求 > - 可用工具 > - 工具能力 > - 性能考虑 ### 选择策略 > - 最佳匹配 > - 优先级排序 > - 负载均衡 > - 缓存利用 #### 5.2 工具调用 ~~~markdown markdown ## 工具调用流程 ### 调用准备 1. 准备工具参数 2. 验证参数有效性 3. 设置调用选项 ### 执行调用 1. 发送调用请求 2. 等待工具响应 3. 处理响应数据 ### 结果处理 1. 解析响应数据 2. 验证结果有效性 3. 传递给下一步 ### 工具调用模式 #### 5.3 顺序调用 ```markdown ## 顺序调用 ### 示例 ~~~python ```python # 读取文件 content = read_file("src/main.py") # 分析代码 analysis = analyze_code(content) # 生成报告 report = generate_report(analysis) ### 特点 > - 简单直观 > - 易于理解 > - 适合线性流程 #### 5.4 条件调用 ~~~ ``markdown `````markdown ## 条件调用 ### 示例 ~~~python ```python # 检查文件是否存在 if file_exists("src/main.py"): # 如果存在，读取并分析 content = read_file("src/main.py") analysis = analyze_code(content) else: # 如果不存在，创建新文件 create_file("src/main.py", template) ### 特点 > - 灵活性高 > - 适应性强 > - 处理分支逻辑 #### 5.5 循环调用 ~~~ ``markdown `````markdown ## 循环调用 ### 示例 ~~~python ```python # 获取所有 Python 文件 files = glob("**/*.py") # 对每个文件执行分析 for file in files: content = read_file(file) analysis = analyze_code(content) save_analysis(file, analysis) ### 特点 > - 批量处理 > - 高效执行 > - 适合重复任务 #### 5.6 并行调用 ~~~ ``markdown `````markdown ## 并行调用 ### 示例 ~~~python ```python # 并行读取多个文件 tasks = [ read_file_async("src/main.py"), read_file_async("src/utils.py"), read_file_async("src/api.py") ] # 等待所有任务完成 results = await asyncio.gather(*tasks) ### 特点 > - 高性能 > - 节省时间 > - 适合独立任务 ## 6. 结果处理 ### 结果类型 #### 6.1 结构化结果 ~~~ ``markdown `````markdown ## 结构化结果 ### 示例 ~~~json ```json { "issues": [ { "type": "security", "severity": "high", "message": "SQL injection vulnerability", "location": "src/main.py:42", "suggestion": "Use parameterized queries" } ], "summary": { "total_issues": 5, "critical": 1, "high": 2, "medium": 2 } } ### 特点 > - 易于解析 > - 结构清晰 > - 适合程序处理 #### 6.2 文本结果 ~~~ ``markdown `````markdown ## 文本结果 ### 示例 代码审查报告 发现的问题： - 使用参数化查询 - 删除未使用的导入 总结： > - 总问题数：5 > - 严重：1 > - 高：2 > - 中：2 ~~~ ### 特点 > - 易于阅读 > - 人类友好 > - 适合展示 #### 6.3 混合结果 ~~~`markdown `markdown ## 混合结果 ### 示例 ~~~markdown ```markdown ## 代码审查报告 ### 结构化数据 ~~~json ```json { "total_issues": 5, "critical": 1 } ### 详细说明 发现 1 个严重问题和 4 个其他问题... ### 建议 建议优先修复严重问题... ### 特点 - 兼顾机器和人类 - 灵活性高 - 适合复杂场景 ~~~ ### 结果验证 #### 6.4 验证检查 ~~~ markdown ## 结果验证 ### 验证项 - 结果完整性 - 数据有效性 - 格式正确性 - 逻辑一致性 ### 验证方法 - 模式匹配 - 类型检查 - 逻辑验证 - 交叉验证 #### 6.5 结果修正 ~~~`markdown ````markdown ## 结果修正 ### 修正策略 > - 自动修正 > - 提示用户 > - 记录问题 > - 重试执行 ### 修正示例 ~~~python ```python # 自动修正格式问题 result = format_result(raw_result) # 提示用户确认 if not confirm_result(result): result = retry_execution() ```## 7. 输出返回 ### 输出格式 #### 7.1 控制台输出 ## 控制台输出 ### 特点 - 实时显示 - 交互友好 - 适合开发调试 ### 示例
正在执行代码审查... ✓ 分析代码结构 ✓ 检查安全问题 ✓ 评估代码质量
审查完成！发现 5 个问题。
bash#### 7.2 文件输出 ## 文件输出 ### 特点 - 持久化存储 - 可追溯 - 适合报告归档 ### 示例 ~~~`bash `bash claude --skill code-review --file src/main.py --output report.md ```> > ~~~ #### 7.3 API 输出 ## API 输出 ### 特点 - 结构化数据 - 易于集成 - 适合自动化 ### 示例 ~~~`json `json { "skill": "code-review", "status": "success", "result": {...} } ```> > ~~~ ### 输出优化 #### 7.4 性能优化 ## 输出性能优化 ### 优化策略 - 流式输出 - 增量更新 - 压缩输出 - 缓存结果 ### 示例 ~~~`python `python # 流式输出大结果 for chunk in stream_result(result): yield chunk ```> > ~~~ #### 7.5 用户体验优化 ## 用户体验优化 ### 优化策略 - 进度显示 - 实时反馈 - 高亮显示 - 交互式输出 ### 示例 ~~~ ``> > 正在执行代码审查... [████████░░] 80% ✓ 分析代码结构 ✓ 检查安全问题 → 评估代码质量... ~~~## 8. 执行监控 ### 监控指标 #### 8.1 性能指标 ## 性能指标 ### 指标类型 - 执行时间 - 内存使用 - CPU 使用 - I/O 操作 ### 监控方式 - 实时监控 - 定期采样 - 事件触发 - 阈值告警
8.2 质量指标
markdown```markdown ## 质量指标 ### 指标类型 - 成功率 - 错误率 - 重试次数 - 用户满意度 ### 监控方式 - 统计分析 - 趋势跟踪 - 异常检测 - 反馈收集 ```### 日志记录 #### 8.3 日志级别 ## 日志级别 ### DEBUG 详细的调试信息 - 每个步骤的详细信息 - 中间结果 - 变量值 ### INFO 一般信息 - 执行开始/结束 - 主要步骤 - 关键决策 ### WARNING 警告信息 - 潜在问题 - 非最佳实践 - 性能警告 ### ERROR 错误信息 - 错误详情 - 堆栈跟踪 - 恢复建议 ``` #### 8.4 日志格式 ~~~markdown ```markdown ## 日志格式 ### 标准格式 ```> [2024-01-15 10:30:45] [INFO] [skill:code-review] 开始执行代码审查 [2024-01-15 10:30:46] [DEBUG] [skill:code-review] 读取文件: src/main.py [2024-01-15 10:30:47] [INFO] [skill:code-review] 分析完成，发现 5 个问题 ### 结构化格式 ~~~`json `json { "timestamp": "2024-01-15T10:30:45Z", "level": "INFO", "skill": "code-review", "message": "开始执行代码审查" } ```> >
总结#
Skills 的执行机制是一个复杂而精密的系统，涉及多个环节和组件。理解这些机制有助于：
- 优化性能：识别和优化性能瓶颈
- 提高可靠性：增强错误处理和恢复能力
- 改善体验：提供更好的用户交互体验
- 扩展功能：基于执行机制开发新功能
在下一节中，我们将探讨 Skills 的上下文管理机制，了解如何高效地管理和利用上下文信息。